<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Creating Providers to use with Zend_Tool_Framework - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.tool.framework.writing-providers.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.tool.framework.writing-providers.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.tool.framework.architecture.html">Architecture</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.tool.framework.html">Zend_Tool_Framework</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.tool.framework.system-providers.html">Shipped System Providers</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.tool.framework.writing-providers" class="section"><div class="info"><h1 class="title">Creating Providers to use with Zend_Tool_Framework</h1></div>
    

    <p class="para">
        In general, a provider, on its own, is nothing more than the shell for a
        developer to bundle up some capabilities they wish to dispatch with the
        command line (or other) clients. It is an analogue to what a
        &quot;controller&quot; is inside of your <acronym class="acronym">MVC</acronym> application.
    </p>

    <div class="section" id="zend.tool.framework.writing-providers.loading"><div class="info"><h1 class="title">How Zend_Tool finds your Providers</h1></div>
        

        <p class="para">
            By default <span class="classname">Zend_Tool</span> uses the IncludePathLoader to find all
            the providers that you can run. It recursivly iterates all
            include path directories and opens all files that end
            with &quot;Manifest.php&quot; or &quot;Provider.php&quot;. All classes in these
            files are inspected if they implement either
            <span class="classname">Zend_Tool_Framework_Provider_Interface</span>
            or <span class="classname">Zend_Tool_Framework_Manifest_ProviderManifestable</span>.
            Instances of the provider interface make up for the real functionality
            and all their public methods are accessible as provider actions.
            The ProviderManifestable interface however requires the implementation of a method
             <span class="methodname">getProviders()</span> which returns an array of
            instantiated provider interface instances.
        </p>

        <p class="para">
            The following naming rules apply on how you can access the providers
            that were found by the IncludePathLoader:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    The last part of your classname split by underscore is used
                    for the provider name, e.g. &quot;My_Provider_Hello&quot; leads to your
                    provider being accessible by the name &quot;hello&quot;.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    If your provider has a method  <span class="methodname">getName()</span>
                    it will be used instead of the previous method to determine
                    the name.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    If your provider has &quot;Provider&quot; as prefix, e.g. it is called
                    <span class="classname">My_HelloProvider</span> it will be stripped
                    from the name so that the provider will be called &quot;hello&quot;.
                </p>
            </li>
        </ul>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                The IncludePathLoader does not follow symlinks, that means
                you cannot link provider functionality into your include paths,
                they have to be physically present in the include paths.
            </p>
        </p></blockquote>

        <div class="example" id="zend.tool.framework.writing-providers.loading.example"><div class="info"><p><b>Example #1 Exposing Your Providers with a Manifest</b></p></div>
            

            <div class="example-contents"><p>
                You can expose your providers to <span class="classname">Zend_Tool</span> by offering a
                manifest with a special filename ending with &quot;Manifest.php&quot;.
                A Provider Manifest is an implementation of the
                <span class="interface">Zend_Tool_Framework_Manifest_ProviderManifestable</span>
                and requires the  <span class="methodname">getProviders()</span> method to return
                an array of instantiated providers. In anticipation of our first
                own provider <span class="classname">My_Component_HelloProvider</span>
                we will create the following manifest:
            </p></div>

            <pre class="programlisting brush: php">
class My_Component_Manifest
    implements Zend_Tool_Framework_Manifest_ProviderManifestable
{
    public function getProviders()
    {
        return array(
            new My_Component_HelloProvider()
        );
    }
}
</pre>

        </div>
    </div>

    <div class="section" id="zend.tool.framework.writing-providers.basic"><div class="info"><h1 class="title">Basic Instructions for Creating Providers</h1></div>
        

        <p class="para">
            As an example, if a developer wants to add the capability of showing
            the version of a datafile that his 3rd party component is working
            from, there is only one class the developer would need to implement.
            Assuming the component is called <span class="classname">My_Component</span>, he would
            create a class named <span class="classname">My_Component_HelloProvider</span> in a
            file named <var class="filename">HelloProvider.php</var> somewhere on the
            <span class="property">include_path</span>. This class would implement
            <span class="classname">Zend_Tool_Framework_Provider_Interface</span>, and the body of
            this file would only have to look like the following:
        </p>

        <pre class="programlisting brush: php">
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say()
    {
        echo &#039;Hello from my provider!&#039;;
    }
}
</pre>


        <p class="para">
            Given that code above, and assuming the developer wishes to access
            this functionality through the console client, the call would look
            like this:
        </p>

        <pre class="programlisting brush: sh">
% zf say hello
Hello from my provider!
</pre>

    </div>

    <div class="section" id="zend.tool.framework.writing-providers.response"><div class="info"><h1 class="title">The response object</h1></div>
        

        <p class="para">
            As discussed in the architecture section <span class="classname">Zend_Tool</span> allows to hook
            different clients for using your <span class="classname">Zend_Tool</span> providers. To keep
            compliant with different clients you should use the response object to return messages
            from your providers instead of using  <span class="methodname">echo()</span> or a similiar
            output mechanism. Rewritting our hello provider with this knowledge it looks like:
        </p>

        <pre class="programlisting brush: php">
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $this-&gt;_registry-&gt;getResponse
                        -&gt;appendContent(&quot;Hello from my provider!&quot;);
    }
}
</pre>


        <p class="para">
            As you can see one has to extend the
            <span class="classname">Zend_Tool_Framework_Provider_Abstract</span> to gain access to the
            Registry which holds the <span class="classname">Zend_Tool_Framework_Client_Response</span>
            instance.
        </p>
    </div>

    <div class="section" id="zend.tool.framework.writing-providers.advanced"><div class="info"><h1 class="title">Advanced Development Information</h1></div>
        

        <div class="section" id="zend.tool.framework.writing-providers.advanced.variables"><div class="info"><h1 class="title">Passing Variables to a Provider</h1></div>
            

            <p class="para">
                The above &quot;Hello World&quot; example is great for simple commands, but
                what about something more advanced? As your scripting and tooling
                needs grow, you might find that you need the ability to accept
                variables. Much like function signatures have parameters, your
                tooling requests can also accept parameters.
            </p>

            <p class="para">
                Just as each tooling request can be isolated to a method within a
                class, the parameters of a tooling request can also be isolated in a
                very well known place. Parameters of the action methods of a
                provider can include the same parameters you want your client to
                utilize when calling that provider and action combination. For
                example, if you wanted to accept a name in the above example, you
                would probably do this in OO code:
            </p>

            <pre class="programlisting brush: php">
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = &#039;Ralph&#039;)
    {
        echo &#039;Hello&#039; . $name . &#039;, from my provider!&#039;;
    }
}
</pre>


            <p class="para">
                The above example can then be called via the command line
                <strong class="command">zf say hello Joe</strong>. &quot;Joe&quot; will be supplied to the provider as
                a parameter of the method call. Also note, as you see that the
                parameter is optional, that means it is also optional on the command
                line, so that <strong class="command">zf say hello</strong> will still work, and default
                to the name &quot;Ralph&quot;.
            </p>
        </div>

        <div class="section" id="zend.tool.framework.writing-providers.advanced.prompt"><div class="info"><h1 class="title">Prompt the User for Input</h1></div>
            

            <p class="para">
                There are cases when the workflow of your provider requires
                to prompt the user for input. This can be done by requesting
                the client to ask for more the required input by calling:
            </p>

            <pre class="programlisting brush: php">
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say($name = &#039;Ralph&#039;)
    {
        $nameResponse = $this-&gt;_registry
                             -&gt;getClient()
                             -&gt;promptInteractiveInput(&quot;Whats your name?&quot;);
        $name = $nameResponse-&gt;getContent();

        echo &#039;Hello&#039; . $name . &#039;, from my provider!&#039;;
    }
}
</pre>


            <p class="para">
                This command throws an exception if the current client is not
                able to handle interactive requests. In case of the default Console Client
                however you will be asked to enter the name.
            </p>
        </div>

        <div class="section" id="zend.tool.framework.writing-providers.advanced.pretendable"><div class="info"><h1 class="title">Pretending to execute a Provider Action</h1></div>
            

            <p class="para">
                Another interesting feature you might wish to implement is
                <em class="emphasis">pretendability</em>. Pretendabilty is the ability
                for your provider to &quot;pretend&quot; as if it is doing the requested
                action and provider combination and give the user as much
                information about what it <em class="emphasis">would</em> do without
                actually doing it. This might be an important notion when doing
                heavy database or filesystem modifications that the user might not
                otherwise want to do.
            </p>

            <p class="para">
                Pretendability is easy to implement. There are two parts to this
                feature: 1) marking the provider as having the ability to &quot;pretend&quot;,
                and 2) checking the request to ensure the current request was indeed
                asked to be &quot;pretended&quot;. This feature is demonstrated in the code
                sample below.
            </p>

            <pre class="programlisting brush: php">
class My_Component_HelloProvider
    extends    Zend_Tool_Framework_Provider_Abstract
    implements Zend_Tool_Framework_Provider_Pretendable
{
    public function say($name = &#039;Ralph&#039;)
    {
        if ($this-&gt;_registry-&gt;getRequest()-&gt;isPretend()) {
            echo &#039;I would say hello to &#039; . $name . &#039;.&#039;;
        } else {
            echo &#039;Hello&#039; . $name . &#039;, from my provider!&#039;;
        }
    }
}
</pre>


            <p class="para">
                To run the provider in pretend mode just call:
            </p>

            <pre class="programlisting brush: sh">
% zf --pretend say hello Ralph
I would say hello Ralph.
</pre>

        </div>

        <div class="section" id="zend.tool.framework.writing-providers.advanced.verbosedebug"><div class="info"><h1 class="title">Verbose and Debug modes</h1></div>
            

            <p class="para">
                You can also run your provider actions in &quot;verbose&quot; or &quot;debug&quot; modes.
                The semantics in regard to this actions have to be implemented by you
                in the context of your provider. You can access debug or verbose modes
                with:
            </p>

            <pre class="programlisting brush: php">
class My_Component_HelloProvider
    implements Zend_Tool_Framework_Provider_Interface
{
    public function say($name = &#039;Ralph&#039;)
    {
        if($this-&gt;_registry-&gt;getRequest()-&gt;isVerbose()) {
            echo &quot;Hello::say has been called\n&quot;;
        }
        if($this-&gt;_registry-&gt;getRequest()-&gt;isDebug()) {
            syslog(LOG_INFO, &quot;Hello::say has been called\n&quot;);
        }
    }
}
</pre>

        </div>

        <div class="section" id="zend.tool.framework.writing-providers.advanced.configstorage"><div class="info"><h1 class="title">Accessing User Config and Storage</h1></div>
            

            <p class="para">
                Using the Enviroment variable <span class="property">ZF_CONFIG_FILE</span> or the
                .zf.ini in your home directory you can inject configuration parameters into
                any <span class="classname">Zend_Tool</span> provider. Access to this configuration is
                available via the registry that is passed to your provider if you extend
                <span class="classname">Zend_Tool_Framework_Provider_Abstract</span>.
            </p>

            <pre class="programlisting brush: php">
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $username = $this-&gt;_registry-&gt;getConfig()-&gt;username;
        if(!empty($username)) {
            echo &quot;Hello $username!&quot;;
        } else {
            echo &quot;Hello!&quot;;
        }
    }
}
</pre>


            <p class="para">
                The returned configuration is of the type
                <span class="classname">Zend_Tool_Framework_Client_Config</span> but internally the
                 <span class="methodname">__get()</span> and  <span class="methodname">__set()</span> magic methods
                proxy to a <span class="classname">Zend_Config</span> of the given configuration type.
            </p>

            <p class="para">
                The storage allows to save arbitrary data for later reference. This can be useful
                for batch processing tasks or for re-runs of your tasks. You can access the storage
                in a similar way like the configuration:
            </p>

            <pre class="programlisting brush: php">
class My_Component_HelloProvider
    extends Zend_Tool_Framework_Provider_Abstract
{
    public function say()
    {
        $aValue = $this-&gt;_registry-&gt;getStorage()-&gt;get(&quot;myUsername&quot;);
        echo &quot;Hello $aValue!&quot;;
    }
}
</pre>


            <p class="para">
                The <acronym class="acronym">API</acronym> of the storage is very simple:
            </p>

            <pre class="programlisting brush: php">
class Zend_Tool_Framework_Client_Storage
{
    public function setAdapter($adapter);
    public function isEnabled();
    public function put($name, $value);
    public function get($name, $defaultValue=null);
    public function has($name);
    public function remove($name);
    public function getStreamUri($name);
}
</pre>


            <div class="important"><b class="important">Important</b>
                <p class="para">
                    When designing your providers that are config or storage aware remember to
                    check if the required user-config or storage keys really exist for a user.
                    You won&#039;t run into fatal errors when none of these are provided though,
                    since empty ones are created upon request.
                </p>
            </div>
        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.tool.framework.architecture.html">Architecture</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.tool.framework.html">Zend_Tool_Framework</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.tool.framework.system-providers.html">Shipped System Providers</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.tool.framework.html">Zend_Tool_Framework</a></li>
  <li><a href="zend.tool.framework.introduction.html">Introduction</a></li>
  <li><a href="zend.tool.framework.clitool.html">Using the CLI Tool</a></li>
  <li><a href="zend.tool.framework.architecture.html">Architecture</a></li>
  <li class="active"><a href="zend.tool.framework.writing-providers.html">Creating Providers to use with Zend_Tool_Framework</a></li>
  <li><a href="zend.tool.framework.system-providers.html">Shipped System Providers</a></li>
  <li><a href="zend.tool.framework.extending.html">Extending and Configuring Zend_Tool_Framework</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>